.so ../bk-macros
.TH "bk prompt" "\*[BKVER]" %E% "\*(BC" "\*(UM"
.SH NAME
bk prompt \- prompt a user with a message
.SH SYNOPSIS
.B bk prompt
.[ARG] opts
.[ARG] message
.SH DESCRIPTION
.B bk prompt
is used to prompt a user with a message, get a positive or negative response,
and exit accordingly.
.LP
This interface may be used for either command line or graphical environments.
.LP
If the environment variable 
.V BK_GUI
is set, then the graphical version will be used instead of the command
line version.
All of the \*[BK] GUI tools set this variable automatically such that any
call to bk prompt from inside the graphical tools will result in a
graphical prompt, including the execution of any user supplied triggers.
.LP
If the environment variable 
.V BK_MSG_GEOM
is set, the graphical tool will use the
value of this variable to locate itself on the screen.  The format of the
variable must be in the form 
.RI + x\c
.RI + y
where
.ARG x
and
.ARG y
are screen coordinates. 
.B bk citool
sets this variable 
automatically such that the prompt will be at the same x/y location as
the upper left corner of citool.
.SH OPTIONS
.TP \-t\*<title\*>
.B \-c
Only for command line prompts, print the message and exit 0.
.tp
.B \-e
Indicates that the prompt is an error message.
.tp
.OPTreq \-f file
Specifies the file contain the message to be displayed.  Unless this option
or the 
.B \-p
option is present,
the last command line argument must be present and is used as the message.
.tp
.B \-g
Override the 
.V BK_GUI
variable and force a command line prompt if called in 
a graphical context.
.tp
.B \-i
Indicates that the prompt is an informational message.
.tp
.OPTreq \-n no
If set, specifies the message for the label in the graphical tool which
is to be used if the user does not agree.  Default is \*(lqNO\*(rq.  Not used
in command line context.
.tp
.B \-o
OK only, clears the default \*(lqNO\*(rq value.
Not used in command line context.
.tp
.OPTreq \-p prog
If set, specifies a program which, when run, will produce the message contents.
.tp
.OPTreq \-t title
If set, specifies the title of the graphical tool.
Default is \*(lqBitKeeper Message\*(rq.
Not used in command line context.
.tp
.OPTreq \-y yes
If set, specifies the message for the label in the graphical tool, or 
the prompt in the command line tool,
which is to be used if the user does agree.  Default is \*(lqOK\*(rq.  
.tp
.B \-w
Indicates that the prompt is a warning message.
.SH EXIT STATUS
.B bk prompt
returns exit status:
.TP
0
if the user said yes
.tp
1
if the user said no
.tp
2
if an error occurred
.SH "SEE ALSO"
.SA citool
.SA triggers
.SH CATEGORY
.B File
